FilBeam x402 v2 idea

Problem Statement

In x402 PoC on Filecoin Beam, we are implementing a design where the content creator manages two payment flows:

• x402 “pay-to-access” gateway is bringing revenue in USDC on Base

• FilBeam retrieval provider is charging egress fees in USDFC on Filecoin

The content creator must periodically top up FilBeam’s payment rails to keep up with access demand.

I see two issues in this design:

• When a piece of content goes viral, the egress quotas will be quickly exhausted, and the content creator won’t be able to top them up fast enough to prevent quota exhaustion, making the content inaccessible.

• It requires a sophisticated user who can navigate the complexity of managing USDC & USDFC payment flows, including cross-currency exchange.

Desired UX

Let’s hide the complexity from the user. Let FilBeam handle the tedious parts and make the user (content creator) experience super easy.

As a content creator:

• I set up an FOC deal that covers storage and upload my content. Storage costs are easy to predict based on the content size and storage duration; therefore, I know how much funding I need to lock in Filecoin Pay.

• I sign up for the Beam-x402 service and set the fee for accessing my content. Beam-x402 charges the retrieval clients in such a way that both my fees and egress costs are covered.

As a retrieval client:

• When I access pay-to-access content, I authorise a single x402 payment to access it, with no prior registrations or subscriptions required.

As a storage provider:

• I am fairly compensated for providing a good retrieval service.

Proposal

Implement a smart contract that will receive x402 payments from the retrieval client and distribute the earnings to all three parties involved in the retrieval:

• Content creator fee

• FilBeam egress fee

• SP egress fee (on cache-miss)

The Process

1. Client asks for PieceCIDv2

2. FilBeam looks up the piece in its index and the access fee set by the storage client.

3. FilBeam parses PieceCIDv2 to extract the content length (size in bytes).

4. FilBeam calculates the retrieval fee as CreatorFee + CdnRequestFee + Size*CdnEgressFee + Size*CacheMissEgressFee
   • We don’t know whether we will be able to serve the request from our cache when the payment is cleared; we must always include the cache-miss fee in the price.
   • The RequestFee should cover FilBeam’s costs to process the request, especially the gas fees.

5. FilBeam returns x402 Payment Required response to the client

6. Client signs the payment authorisation

7. Client re-requests the content with the payment authorisation included

8. FilBeam checks if the requested content is cached:

9. [Cache-hit]
   1. FilBeam invokes the smart contract method for the cache-hit path and provides the following arguments:
      1. payment authorisation from the client
      2. content creator’s wallet address
      3. FilBeam’s wallet address
   2. The smart contract executes the payment transaction and receives funds from the client.
   3. The smart contract splits the unused cache-miss fee between the content creator and FilBeam (e.g., 50:50). This incentivises content creators to produce highly cacheable content and encourages FilBeam to implement an effective caching strategy.
   4. The smart contract transfers the content creator's fee and the portion of the cache-miss fee to the content creator’s address.
   5. The smart contract transfers the CDN fees and the portion of the cache-miss fee to FilBeam’s wallet.
   6. After receiving TX confirmation, FilBeam serves the requested content from the cache.

      Note: There is a race condition we will need to solve: There is a delay between the time when we check the cache for the requested content and the time we request the cached content. We must ensure the requested content is not evicted from the cache while we are waiting for the payment TX confirmation.

10. [Cache-miss]
    1. FilBeam decides which SP to use for the cache-miss request
    2. FilBeam invokes the smart contract method for the cache-miss path and provides the following arguments:
       1. payment authorisation from the client
       2. content creator’s wallet address
       3. FilBeam’s wallet address
       4. address of the SP handling the cache-miss request
    3. The smart contract executes the payment transaction and receives funds from the client.
    4. The smart contract transfers the content creator's fee and the portion of the cache-miss fee to the content creator’s address.
    5. The smart contract transfers the CDN fees and the portion of the cache-miss fee to FilBeam’s wallet.
    6. The smart contract signs a payment authorisation from contract’s balance to the SP wallet, and returns the signed message to the caller (FilBeam).

       Note: Since this return value is public, we need to encrypt it so that only FilBeam can use the the authorisation. Can we encrypt the message using FilBeam’s public key (wallet address)?

    7. After receiving TX confirmation, FilBeam decodes the payment authorisation.
    8. FilBeam requests the content from the selected SP and includes the payment authorisation obtained from the smart contract. (This will be a regular x402 request with payment denominated in USDC on Base.)
    9. SP settles the payment and returns back the requested content
    10. FilBeam stores the content in the cache and returns it back to the client

A Faster Alternative

In the proposal above, the cache-miss path waits for two transactions to settle, which may be considered too slow by some retrieval clients. A faster alternative is for the smart contract to transfer the cache-miss egress fee immediately to the SP.

1. The smart contract transfers the cache-miss egress fee to the SP wallet.

2. After receiving TX confirmation, FilBeam requests the content from the SP. Instead of including a payment authorisation, the request includes the TX hash, which allows the SP to verify that the payment has already been made.
   The downside: This is a custom Beam protocol, not a regular x402 payment mechanism. The SPs are required to support our custom protocol. Can we contribute this protocol to the x402 spec?

Open Questions

1. How to handle failed cache-miss requests? Vanilla FilBeam implements a fallback mechanism - if the first SP does not return the requested content, we reach out to the next SP storing the same content, and so on.
   This is not possible in the proposed design, because the cache-miss egress payment is tied to the SP selected for the first retrieval attempt.

2. Compliance with Payment Processor regulations. Since the smart contract handles the payments, can we plausibly claim that FilBeam is not a payment processor?
   • FilBeam provides the recipient wallet addresses (client, FilBeam, SP) in the smart contract method arguments. If that creates a problem, we can look into ways to move that information into the payment authorisation metadata. (Unfortunately, x402 currently does not allow any metadata in the payment authorisation.)
   • We can deploy one smart contract per content creator (as a one-time initial setup), so that it’s the content creator who deployed the immutable smart contract that’s managing the payments. The address of this smart contract can then be specified in the FOC deal metadata as the recipient.